/* -*-mode:java; c-basic-offset:2; indent-tabs-mode:nil -*- */
/*
Copyright (c) 2004-2011 ymnk, JCraft,Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice,
     this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright 
     notice, this list of conditions and the following disclaimer in 
     the documentation and/or other materials provided with the distribution.

  3. The names of the authors may not be used to endorse or promote products
     derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JCRAFT,
INC. OR ANY CONTRIBUTORS TO THIS SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

package com.yisin.ssh2.jsch;

/**
 * Usually not to be used by applications.
 *<p>
 * Encapsulates a GSS context, i.e. an implementation of the
 * GSS API. This is used by {@link UserAuthGSSAPIWithMIC} to do the
 * actual cryptographic work. (See this class for a description on how this
 * interface is used.)
 *</p>
 *<p>
 * This interface only contains the methods needed for GSS-API authentication,
 * not the full GSS API.
 *</p>
 *<p>
 * An implementation of this interface is included in the JSch library,
 *  based on the {@linkplain org.ietf.jgss GSS API} included in the
 *  Java SE from 1.4 on, using object ID {@code 1.2.840.113554.1.2.2}, i.e.
 *  Kerberos v5 as defined in RFC 1964.
 *</p>
 *
 * @see org.ietf.jgss.GSSContext
 * @see <a href="http://tools.ietf.org/html/rfc2743">RFC 2743,
 *    Generic Security Service Application Program Interface
 *    Version 2, Update 1</a>
 * @see <a href="http://tools.ietf.org/html/rfc5653">RFC 5653: Generic Security Service API Version 2: Java Bindings Update</a>
 * @see <a href="http://tools.ietf.org/html/rfc4462">RFC 4462:
 *     Generic Security Service Application Program Interface (GSS-API)
 *  Authentication and Key Exchange for the Secure Shell (SSH) Protocol</a>
 * @see <a href="http://tools.ietf.org/html/rfc1964">RFC 1964,
 *    The Kerberos Version 5 GSS-API Mechanism</a>
 */
public interface GSSContext{
  /**
   * creates the context.
   * @param user the user name.
   * @param host the server's name.
   * @see org.ietf.jgss.GSSManager#createContext
   */
  public void create(String user, String host) throws JSchException;

  /**
   * Checks is the context establishing already succeeded.
   */
  public boolean isEstablished();

  /**
   * Tries to establish the secure context by processing a token
   * from the server and (maybe) creating a new token to send to
   * the server.
   * @param token an array containing the token received from the server.
   *    At the start, this will be an empty array.
   * @param s the index in {@code token} where the token actually starts.
   * @param l the length of the token.
   * @return the token to be sent to the server (if length > 0).
   * @see org.ietf.jgss.GSSContext#initSecContext
   */
  public byte[] init(byte[] token, int s, int l) throws JSchException;

  /**
   * calculates a Message Integrity Code for a message.
   * @param message an array containing the message for which the
   *    the code should be calculated.
   * @param s the index in {@code message} where the message actually
   *    starts
   * @param l the length of the message.
   * @return a token containing the MIC for the message.
   * @see org.ietf.jgss.GSSContext#getMic
   */
  public byte[] getMIC(byte[] message, int s, int l);

  /**
   * Disposes this context, releasing any system resources
   * and stored cryptographic information. The context can't be used
   * after this call.
   */
  public void dispose();
}
